HostMonitor provides different ways (23 methods!) to respond to failed services. Audio and visual notifications can alert people near the machine. E-mail and pager notifications can be used to inform a wider range of remote operators. Some of the actions HostMonitor can take will try to recover from a failure automatically without human intervention.

Each test can be set up with an individual action profile, and each action profile may contain a number of alert actions that can be launched in a predefined order depending on the test results. Here is a list of available actions to kick off in response to a problem:

• Show message
• Play sound
• Generate reports
• Execute external program
  
  
• Send e-mail
• Send message to alphanumeric pager (TAP protocol)
• Send message to alphanumeric pager (SNPP protocol)
• Send message to numeric pager
• Send message to ICQ
  
  
• Stop service
• Start service
• Restart service
• Remote reboot
• Local reboot
  
  
• Log Event
• SQL Query
• Send data to TCP/UDP port
• Syslog
• SNMP Set
  
• SNMP Trap
  
  
• Dial-up to network
• Disconnect dial-up connection
  
  
• Repeat test
• Change test interval
• Execute HMS script

To work with action profiles you can use the Action Profiles dialog. To bring up this dialog use menu Profiles->Action profiles in HostMonitor's main window or appropriate buttons in the Test Properties dialogs.

In the upper part of the dialog you can see a list of Action Profiles and buttons (New, Copy, Rename, Delete) that allow you to modify this list. Each of the Action Profile has 2 sets of actions: ½Bad╗ actions and ½Good╗ actions. The sets of actions and buttons for modifying these actions (Add/Edit/Del) you can find in the lower part of the dialog.

You have to understand difference between actions profile and actions: each test has link to one (only one) of the action profiles, and each of the action profiles may contain a number of actions that can be launched in a predefined order depending on the test results.


Assume action profile has been assigned to the test. In this case every time after test is done and log file was updated HostMonitor performs actions that are assigned in the related list: it uses list of "Good" actions if test has "Good" status, and uses list of "Bad" actions if test has "Bad" status. To determine which actions from the list should be executed and which should not, HostMonitor uses 3 properties that each "standard" action has:

Action properties are defined in the Action Properties dialog. Some properties are common across all action types. However, each type of action has a set of parameters that are specific to the action type. Let's have a look at the common properties first (these parameters located in the upper half of the Action Properties dialog):

Action name
The name of the action; HostMonitor auto populates this field with a suggested name based on the type of action; you can change that name to whatever name you want.

Condition to start action
There are 3 different types of starting condition:

1. standard mode
   Standard actions are those actions that are performed by HostMonitor after a test had returned specified result for specified number of times. Following 3 parameters defines when action should be executed:
   
   Start when N consecutive Bad/Good results occur
   This parameter determines when to execute an action. For example you want to send a message to a network administrator's pager after three unsuccessful tests of the web server consecutively, set this parameter to 3. If you want to start action right after the test status was changed, set parameter to 1.
   
   Repeat: N times; or until status changes
   Defines the number of repeats of the action if the status of the test was not changed. For example if you want to send an e-mail to a network administrator only once when test status changes, set this parameter to 1. If you need to execute action every time when test failed, set this option to "until status changes".
   
   Action depends on "bad" one
   This optional parameter is available for "Good" actions only. You can set "Good" action dependable on a "Bad" action. Why do you need it? For example you defined "Bad" action to send an e-mail notification to the network administrator when test fails 3 times consecutively (start when 3 consecutive "Bad" results occur), also you defined ½Good╗ action to send a notification when the test status changes to "Good". What will happen if test fails 1 or 2 times and after this it restores "Good" status? HostMonitor will not send a notification about failure (because test did not fail 3 times) but the program will send notification about restoring "Good" status. To avoid unnecessary "Good" action execution you can mark "Action depends on "bad" one" option and select "Bad" action. In this case HostMonitor will start "Good" action only if corresponding "Bad" action was executed.
   
   Several examples:
   
   Example 1: You want a fresh network stats report to be posted on your intranet web server every time the test finds the server to be up and running. This can be done simply by adding the following "Good" action to the action profile:
     Action: Generate reports
     Start when: 1 consecutive "good" result occur
     Retries: until status changes
   
   Example 2: When some critical service dies, you want the server to automatically reboot. If that does not help, an e-mail should be sent to the on-call technician. If, however, the server remains silent during the next three tests, the network administrator is to be paged until the server is brought back up. To implement this behavior, create an action profile with three "Bad" actions defined like these:

   1. Action: remote reboot
      Start when: 1 consecutive "bad" result occur
      Retries: 1
   2. Action: send e-mail
      Start when: 2 consecutive "bad" results occur
      Retries: 1
   3. Action: send message to pager
      Start when: 5 consecutive "bad" results occur
      Retries: until status changes
   
   

2. advanced mode
   Advanced mode allows you to use logical expression as a condition that triggers the alert action. An alert action is performed when a logical expression of a condition is true. In these expressions you can use:

   • numbers and strings (in quotes). Strings that contain a number plus one of the following unit specificators [ms, Kb, Mb, Gb, %] are compared as numbers, so that '900 Kb' is less than '9 Mb'
   • macro variables related to the current test or to any other test;
   • global macro variables;
   • logical operators [and, or, not, <, >, >=, <=, ==, <>];
   • arithmetic operators div, mod. The value of (x div y) is the value of x divided by y and then rounded in the direction of zero to the nearest integer; 'mod' operator returns the remainder obtained by dividing its operands (in other words, (x mod y) == x - (x div y) * y);
   • parentheses. In complex expressions, common rules of precedence determine the order in which operations are performed:

     Operators	Precedence
     not	first (highest)
     div, mod	second
     <, >, >=, <=, ==, <>	Third
     and, or	fourth (lowest)

     An operator with higher precedence is evaluated before an operator with lower precedence, while operators of equal precedence associate to the left. You can use parentheses to override precedence rules. An expression within parentheses is evaluated first and then its result is treated as a single operand.
   
   Advanced mode is more complicated than standard but is very very flexible. Just several simple examples:
   • '%SimpleStatus%'<>'UP' - action will be executed every time the test is performed and status of the test is not "good";
   • '%Status%'<>'%LastStatus%' - action will be executed every time the test status changes;
   • ('%Status%'=='No answer') and ('%LastStatus%'=='Host is alive') - action will be executed when the test status changes from "Host is alive" to "No answer"
   • ('%SimpleStatus%'=='DOWN') and (%Recurrences%==5) - action will be executed if the fifth attempt of a test in a row fails
   • ('%SimpleStatus%'=='DOWN') and (%Recurrences% mod 3==1) - action will be executed after 1st, 4th, 7th, 10th,, 13th, à consecutive failed test
   • ((%Reply%>200) and (%Reply%<800)) or ('::Main Router::%SimpleStatus%'=='DOWN') - action will be executed when "Reply" value of the test is between 200 and 800 or status of the "Main Router" test is "No answer" or "Bad".



3. on the schedule
   Unlike standard and advanced actions that are triggered by events related only to the tests, scheduled actions are conformable to the schedule. They also may be triggered by some "global" events (e.g. HostMonitor can start "scheduled" actions when user stops monitoring). There are several places where you can use scheduled actions:

   • The Scheduler itself - a tab in the Options dialog allows you to execute up to 5 alert profiles by a schedule. E.g. HostMonitor may execute one profile every 1 hour and execute another profile every Monday at 21:00;
   • Reports page in the Options dialog: now HostMonitor can execute alert profile after reports were generated;
   • Reports page in the Folder Properties dialog;
   • Statistics page in the Folder Properties dialog: HostMonitor can execute alert profile before resetting the statistics;
   • Pause dialog: HostMonitor can execute alert profiles every time user starts or stops monitoring or when the user enables/disables alerts.
   It is a good idea to create separate action profiles for standard/advanced actions and for scheduled actions.

Executing this action, HostMonitor will display a popup window with information about state of the test. All settings for this window (position, time to display, etc) may be setup on the "Msg Window" page in the Options dialog.

See also common action parameters

This action designed to play a sound file (WAV, MID, etc). In addition to the common action parameters, the ½Play sound╗ action has the following options:

Sound file
Specify full path to the sound file or click small button on the right side and select file from the Open File dialog.

Show WakeUP window and play sound repeatedly
With this option enabled HostMonitor will display a popup window with information about the event and will play a sound repeatedly until you click "Stop" button.

HostMonitor can generate reports in HTML, DBF, WML, and Text formats. If you want to generate reports when some test changes status, add "Generate reports" action into action profile. In addition to common action parameters select one of the options:

Generate reports for the containing folder
With this option selected HostMonitor will create reports for the Folder in which the test causing actions are contained. This option useful when you want to assign one action profile to many different tests that located in different Folders. Each test will create reports for its own Folder.

"Generate reports for .."
Choose this option and select the Folder from drop-down list if you need to create reports for some specific Folder.

Recursive mode
This parameter defines whether HostMonitor includes subfolders to the report or not. Choose one of the following options:

- Single folder	Include specified folder only (no subfolders)
- Folder & all subfolders	Include specified folder and all descendant subfolders
- Folder & subfolders with inherited settings	Incude specified folder and subfolder which inherit reports' settings from the parent folder

As you see you do not specify report to generate directly. That is because each Folder contains list of up to 6 reports or Folder can inherit this list from the Parent Folder. For more information about Folders, refer to "TestList & Windows" section of this documentation.
Also you can use "Execute HMS script" action to generate some specific reports. For more information about Reports, refer to "Log&Reports" section of this documentation.

Name of this action tells for it self, it launches specified external application. In addition to the common action parameters it has 2 more parameters:

Command line
Specify command line to launch external application. Macro variables may be used in the command line.

Window mode
This parameter specifies how the application window will be shown. Choose one of the possible options:

SW_SHOWNORMAL	-	displays an application window in its original size and position.
SW_HIDE	-	starts application without displaying its window.
SW_MAXIMIZE	-	displays an application window as a maximized window.
SW_MINIMIZE	-	displays an application window as a minimized window.
SW_SHOWMINNOACTIVE	-	displays an application window as a minimized window. The active window remains active.
SW_SHOWNOACTIVATE	-	displays an application window in its original size and position. The active window remains active.

HostMonitor can send e-mail notification (that includes the problem data) to a mailbox, a pager or a mobile phone using any SMTP server. On the Mailer settings page in the Options dialog setup the parameters of your Primary and Backup SMTP servers (address of the server, port, authentication method, login, password, etc).
In addition to the common action parameters, the ½Send e-mail╗ action has the following parameters:

From
Specify the email address of the sender.

To
Specify a list of destinations for the mail message. A copy of the message is sent to each of them, and a "To" SMTP header is created containing the destination addresses. More than one destination addresses separating with a semicolon (;) Macro variables are supported in this field.

Subject
The subject of the mail message. Macro variables may be used in the subject line.

Mail template
Select one of the existing mail templates that will be used as a body of the mail (text) from drop down list or click button to bring up the Mail Templates dialog and create mail template for your preferences. Macro variables are supported in message templates to be substituted with their actual values at the message generation time. Also you can specify a particular character set for your mail templates.

Attach file
You can mark this option and select file that will be attached to the message. Enter the path manually or press button to select a file from the Open File dialog.

HostMonitor can send message to your alpha-numeric pager(s) using the TAP protocol. For this you need a modem and a phone line connected to the computer. On the Pagers page in Options dialog you can setup general modem settings.
In addition to the common action parameters, you will need to fill out some information about the paging company and pager of the person you wish to send a message to. These parameters can be different for each action.

What do you need to know about the paging company of the pager?

Access Number
You need to know the paging terminals alphanumeric paging access telephone number. This is the phone number of the modem at the paging company that will receive the message using the TAP protocol. This number is the same for everybody that has a pager from that company. Many carriers will offer 800 numbers - especially the nationwide guys like SkyPage or Mobilcomm. THIS IS DIFFERENT FROM THE PAGER TELEPHONE NUMBER. You may include dashes and commas like any other modem phone number (a comma usually pauses 2 seconds - i.e. 9,444-4444).
By putting "DIRECT" in this string, the program assumes a direct connection. No dialing takes place and DTR is NEVER dropped. If the phone number is in the format +1 (303) 799-0055 that is called canonical form, the access phone number will be TAPI converted to a dialable number. In this manner you can always send the area code and it will know if it is a local or long distance call. It will also dial the prefix digit (such as 9) to get outside line - etc.

Password
Does your paging carrier require a password? Most US companies DO NOT. In this case, the program sends six zeros as the password. This is the standard way of doing it. If you require a special password, define it in this field.

Max characters per block
This is the number of characters the paging company allows per message block. This number varies widely from company to company. Some are as small as 60 characters and some are as big as 1000 characters. The norms seem to be 80 and 230 characters per block. You will need to find out this information or learn this through trial and error. If the message you pass is bigger than the character per block limitation, the program automatically splits your message up into multiple blocks, so the recipient gets the entire message. However, he/she does get a different page for each block.

Parity
Specifies the parity, data bits, stop bits that the paging company's alpha access port communicates at. In very rare cases the paging terminal require N,8,1 rather than E,7,1.

What do you need to know about the Pager?

Pager ID
The only thing you need to know about the pager is the pager phone number or the Pager ID (Alpha PIN). DO NOT INCLUDE ANY DASHES in this number.

Mail template
Select one of the existing mail templates (that will be used for the message generation) from drop down list or click button to bring up the Mail Templates dialog and to create the template for your preferences. Macro variables are supported in message templates to be substituted with their actual values at the message generation time.

This action sends a message to a pager using the SNPP protocol; unlike TAP protocol, which employs the modem, SNPP is built on top of TCP/IP to send messages via an Internet connection.
In addition to the common action parameters, ½Send message to pager (SNPP)╗ action has the following options:

PagerID
Specify the Pager ID (PID) number.

Mail template
Select one of the existing mail templates (that will be used for the message generation) from drop down list or click button to bring up the Mail Templates dialog and to create the template for your preferences. Macro variables are supported in message templates to be substituted with their actual values at the message generation time.

Server
Specify the name or IP address of the SNPP server.

Port
The default SNPP port is 444, but you can specify a non-standard port.

Login as
This parameter allows for a session login ID to be specified. It is used to validate the person attempting to access the paging terminal. If this option is disabled, "anonymous" user status is assumed.

HostMonitor can send messages to "numeric only" pagers (beepers). TAP protocol is not used in these cases. The program simply takes the phone line off-hook, dials the pager phone number, waits specified number of seconds, touch tones the digits to be displayed on the pager and hangs up. This method does not guarantee delivery to the paging company. It just dials and hopes it works.
In addition to the common action parameters, the ½Send message to beeper╗ action has the following options:

Beeper #
Enter the telephone number for the beeper. This is the number on the beeper that people call to touch tone in digits. You may use a comma in the number, the comma tells the modem to wait 2 seconds.

Delay
Specify how many seconds to delay from the time the beeper number dialed and the display digits are dialed.

Send message
This parameter defines the digits that will appear on the pager. You may use macro variables (e.g. "%StatusID%", "%HostID%", "%CommentID%") and comma (for 2 seconds delay).

Termination string
Define the modem command used to terminate a call. Normally, this parameter is empty and HostMonitor uses a "#,H;" to finish the call. The # is normally used when you have finished touch-toning in the digits to send to the pager. The comma tells the modem to wait 2 seconds before hanging up. The "H" tells the modem to hang up when it is done. The semi-colon puts the modem in command mode and sends an OK to the computer when it has finished dialing.

Setup general paging settings on the Pagers page in Options dialog.

Sends a message through an ICQ web server to the specified ICQ user. In addition to the common action parameters, the ½Send message to ICQ╗ action has the following options:

From (name)
Specify the name of the sender.

From (e-mail)
Specify the email address of the sender.

To ICQ #
Specify the ICQ# to whom the message will be sent.

Subject
The subject of the message. Macro variables may be used in the subject line.

Mail template
Select one of the existing mail templates (that will be used for the message generation) from drop down list or click button to bring up the Mail Templates dialog and create template for your preferences. Macro variables are supported in message templates to be substituted with their actual values at the message generation time.

Microsoft Windows NT/2000/XP supports an application type known as a service. HostMonitor can stop these applications on local or remote computers (if you have an account with privileges for starting/stopping services).
In addition to the common action parameters, the ½Stop service╗ action has the following options:

Computer name
Provide the name of the target system (the target computer name must be prefixed by "\\") or select the "<local computer>" item to stop the service on a local machine. You may use the "Browse network" button to select a computer from the list. Also you can use macro variables (e.g. %ServiceComp%, %ServiceName%) in this field.

Service name
Name of the service to stop. You may select the service from the drop-down list. You can use macro variables in this field as well.

Parameters
Parameters string passed to the service.

Connect as
To stop a service on remote Windows system you may mark this options and provide a username and a password for a connection to the target computer.

Microsoft Windows NT/2000/XP supports an application type known as a service. HostMonitor can start these applications on local or remote computers (if you have an account with privileges for starting/stopping services).
In addition to the common action parameters, the ½Start service╗ action has the following options:

Computer name
Provide the name of the target system (the target computer name must be prefixed by "\\") or select the "<local computer>" item to start the service on a local machine. You may use the "Browse network" button to select a computer from the list. Also you can use macro variables (e.g. %ServiceComp%, %ServiceName%) in this field.

Service name
Name of the service to start. You may select the service from the drop-down list. You can use macro variables in this field as well.

Parameters
Parameters string passed to the service.

Connect as
To start a service on remote Windows system you may mark this options and provide a username and a password for a connection to the target computer.

Microsoft Windows NT/2000/XP supports an application type known as a service. HostMonitor can restart these applications on local or remote computers (if you have an account with privileges for starting/stopping services).
In addition to the common action parameters, the ½Restart service╗ action has the following options:

Computer name
Provide the name of the target system (the target computer name must be prefixed by "\\") or select the "<local computer>" item to restart the service on a local machine. You may use the "Browse network" button to select a computer from the list. Also you can use macro variables (e.g. %ServiceComp%, %ServiceName%) in this field.

Service name
Name of the service to restart. You may select the service from the drop-down list. You can use macro variables in this field as well.

Parameters
Parameters string passed to the service.

Connect as
To restart a service on remote Windows system you may mark this options and provide a username and a password for a connection to the target computer.

HostMonitor can reboot or shut down remote Windows NT/2000/XP system. To shut down a remote computer, the calling process must have the SE_REMOTE_SHUTDOWN_NAME privilege on the target system. By default Administrators have this privilege.
In addition to the common action parameters, define the following options:

Computer name
Provide the name of the target system (the target computer name must be prefixed by "\\"). You may use the "Browse network" button to select a computer from the list. Also you can use macro variables (e.g. %HostAddr%) in this field.

Message to display
Provide a message to display on the remote system before shutdown.

Time to display
If time is not zero, system displays a dialog box on the specified computer. The dialog box displays the name of the user who called the function, displays the message, and prompts the user to log off. The dialog box beeps when it is created and remains on top of other windows in the system. The dialog box can be moved but not closed. A timer counts down the remaining time before a forced shutdown. If the user logs off, the system shuts down immediately. Otherwise, the computer is shut down when the timer expires.
If you set time to zero, the computer shuts down without displaying the dialog box.

Method
Select one of the 2 options:

HostMonitor can reboot local Windows 9x/ME/NT/2000/XP system. In addition to the common action parameters, choose 1 of 4 reboot Methods:

Event logging in Microsoft Windows NT/2000/XP provides a standard, centralized way for applications (and the operating system) to record important software and hardware events. The event-logging service stores events from various sources in a single collection called an event log.
The Log Event action form allows you to add or edit an action that will log a record to the Event Log. Entries in the event log can be viewed with the Event Viewer or used by the other software utilities that perform centralized alerting from the event log.
In addition to the common action parameters, the "Log Event" action has the following parameters:

Computer
The UNC (Universal Naming Convention) name of the server on which the event should be recorded (the target computer name must be prefixed by "\\"). Type the UNC or select the "<local computer>" item. You can use macro variables (e.g. %HostAddr%) in this field.

Log
Provide name of the log file. This can be the Application, Security, System log file, or a custom registered log file.

Event source
Select source of the events from drop down list. You can use macro variables (e.g. %CommentLine2%) in this field.

Event type
Choose type of the event to be logged. This parameter can have one of the following values:

Executes an SQL query against the specified ODBC data source. In addition to the common action parameters, the ½SQL Query ╗ action has the following parameters:

ODBC data source
Choose one of ODBC data sources available on your system.

Login
Specify user identifier, if necessary.

Password
Specify password, if necessary.

SQL Query
Specify SQL query to execute. Macro variables are supported in the query to be substituted with their actual values at the action execution time.

Timeout
Specify the number of seconds to wait for a login request to complete.

Sends data to the specified host using TCP or UDP protocol. In addition to the common action parameters, the ½Send data to TCP/UDP port╗ action has the following options:

Server
This is the domain name or the IP address of the target host.

Port
A valid port number (a value between 1 and 65535) is required for the connection to take place.

Protocol
Select the protocol to use: TCP or UDP.

Init packet (string) to send
Provide data to send to the host. In this field you can use regular text; macro variables; and sequences formatted %XX where XX is a hexadecimal code of a character (byte). E.g. define this parameter like: ½%TestName% %0D%0A %Status% %0D%0A %DateTime%╗ to send 3 text lines with the information about the test, its status, and current time.

Wait for answer
Specify how many seconds HostMonitor should wait for an answer before sending Final packet.

Final packet (string) to send
Provide this parameter if you need to send two information packets with the pause between them to the host. The same as for the Init Packet parameter, in this field you can use regular text; macro variables; and sequences formatted %XX where XX is a hexadecimal code of a character (byte).

For example using this action you can perform HTTP request:
Server: www.myserver.com
Port: 80
Protocol: TCP
Init packet: GET http://www.myserver.com/cgi-bin/addevent.php?Test=%TestName%&Status=%Status%
Wait for answer: 0

This action sends data using the Syslog protocol. Syslog is the standard event logging subsystem for Unix, also you can find Syslog Daemon for Windows (e.g. Kiwi Syslog Daemon). Syslog Daemon receives standard UDP Syslog messages sent from routers, switches, UNIX hosts, HostMonitor, other network devices and can displays the details on screen, log to files, terminal devices, etc. Syslog also allows you to forward log entries to another machine for processing, in this way syslog functions as a distributed error manager.
In addition to the common action parameters, the ½Syslog╗ action has the following parameters:

Server
This is the name or IP address of the Syslog server.

Port
The default SNPP port is 514, but you can specify a non-standard port.

Message
Provide text message to send. Macro variables are supported in the message to be substituted with their actual values at the action execution time.

Severity
Log messages are prioritized by a combination of facility and urgency level. Levels (severity) can be considered various levels of a problem (e.g. warning, error, emergency) whereas facilities are considered to be service areas (e.g. printing, email, network, etc). The levels available are the following:

-	Emergency	A panic condition. System is unusable.
-	Alert	A condition that should be corrected immediately, such as a corrupted system database.
-	Critical	Critical conditions, e.g., hard device errors.
-	Error	Errors.
-	Warning	Warning messages.
-	Notice	Conditions that are not error conditions, but should possibly be handled specially.
-	Info	Informational messages.
-	Debug	Messages that contain information normally of use only when debugging a program.

Facility
Facility is a number that considered as a service area. The various facilities are listed below:

0	kernel messages
1	user-level messages (messages generated by random user processes)
2	mail system
3	system daemons
4	security/authorization messages
5	messages generated internally by syslogd
6	line printer subsystem
7	network news subsystem
8	UUCP subsystem
9	clock daemon
10	security/authorization messages
11	FTP daemon
12	NTP subsystem
13	log audit
14	log alert
15	clock daemon
16-23	reserved for local use

Sets data on the local or remote system using the SNMP protocol. The Simple Network Management Protocol is the Internet standard protocol for exchanging management information between management console applications and managed entities (hosts, routers, bridges, hubs, etc). Using this protocol HostMonitor can change settings of your network devices.
In addition to the common action parameters, the ½SNMP Set╗ action has the following parameters:

Agent address
Provide address of the target system. Specify either a dotted-decimal IP address or a host name that can be resolved to an IP address, an IPX address (in 8.12 notation), or an Ethernet address. You can use macro variables (e.g. %HostAddr%) in this field.

Community
Specify the SNMP community name used when communicating with the device specified in the Agent Address parameter. By default on SNMP systems this is "PUBLIC" but it can be different on your systems.

Timeout
This is the amount of time in seconds the program will wait for a response from the server before the request fails.

Retries
Specify the communications retries count.

OID
The name that uniquely identifies the object, the value of which you have to change. For example OID "1.3.6.1.2.1.2.1" represents the number of network interfaces on which system can send/receive IP datagrams; OID "1.3.6.1.2.1.6.9" represents the number of TCP connections for which the current state is either ESTABLISHED or CLOSE-WAIT; etc. To get a list of valid OIDs for your SNMP enabled devices you should contact the vendor of the device. They should be able to give you a MIB file that contains all the OIDs for the device.

Set value
Define a new value for the object that HostMonitor has to set (please note some object can be read-only). Use "Get current value" button to retrieve current value of the object.

Sends a message to the Management Station using the SNMP protocol. The SNMP (Simple Network Management Protocol) is the Internet standard protocol for exchanging management information between management console applications and managed entities (hosts, routers, bridges, hubs, etc).
In addition to the common action parameters, the "SNMP Trap" action has the following parameters:

Destination address
Enter the domain name or IP address of the machine that will receive SNMP Trap messages. This machine should be running a SNMP console in order to receive the trap message. You can use macro variables (e.g. %HostAddr%) in this field.

Agent address
Provide IP address of the agent that generated the SNMP Trap. If you keep default value "localhost", HostMonitor will use IP address of the system where it is running. You can use macro variables (e.g. %HostAddr%) in this field.

Community
Specify the SNMP community name used for this trap. The default community for most systems is "public". The community string must match the community string used by the SNMP console.

Enterprise
Identifies the type of the object causing the trap. You can use macro variables (e.g. %CommentLine1%) in this field.

Trap type
Choose one of the generic trap types:

This action allows establishing dial-up connection to a network. E.g. HostMonitor can establish backup connection in case of primary channel malfunction. In addition to the common action parameters, the ½Dial-up to the network╗ action has the following options:

Dial-up connection
Select from drop down list the remote access entry to establish the connection.

User name
Specify the user's name. This parameter is used to authenticate the user's access to the remote access server. If the user name is empty string (""), HostMonitor uses the user name of the current logon context for authentication. For a user-mode application, RAS uses the credentials of the currently logged-on interactive user. For a Win32 service process, RAS uses the credentials associated with the service.

Password
Specify the user's password. This parameter is used to authenticate the user's access to the remote access server. If the password is empty string (""), HostMonitor uses the password of the current logon context for authentication. For a user-mode application, RAS uses the credentials of the currently logged-on interactive user. For a Win32 service process, RAS uses the credentials associated with the service.

Save password
This option has sense only if Password parameter is not an empty string. Specifies whether to save the password (in the phone-book entry) for the user indicated by User Name parameter or not. If "Save password" option is disabled, the password will be removed. Disabling option is equivalent to checking the "Unsave Password" checkbox in Dial-Up Networking dialog.

Show dial-up dialog
With this option enabled HostMonitor will display a popup window when establishing the connection, and will display dial-up process information in it.

Retries
Set the number of times the dial-up connection is automatically redialed if the first attempt to connect fails.

Purpose of this action is to drop the specified dial-up connection (e.g. in case if the main channel will restore its functioning). In addition to the common action parameters, the ½Disconnect from network╗ action has only one parameter:

Dial-up connection
Select from drop down list the remote access connection to terminate.

This action simply forces the program to perform the test one more time (not waiting until time of the test interval is elapsed). It does not have any extra parameters except common action parameters.

This action can be helpful in situations when the condition being checked is not stable. If, for some reason, the accuracy of the test is questionable, you can add this action into alert profile, and take the necessary measures based on the results of the follow-up test.

This action allows changing the test time interval. In addition to the common action parameters choose one of the options:

This is very flexible action because script file may contain various commands for the program and tests control. In addition to the common action parameters, the ½Execute HMS script╗ action has only one parameter:
Script file - specify full path to the script file or click small button on right side and select file from the Open File dialog.

HostMonitor Script file (file extension .HMS) is a text file that contains commands for HostMonitor. You can create and edit script file using any text editor (e.g. notepad). Some examples when this action method can be useful:

1. Assuming that you have dynamically (real-time) database with list of servers to monitor. When database is changing HostMonitor can reload the list of tests or import new tests automatically. To implement this behavior add test to monitor changes in the database (e.g. "File Integrity" test or "ODBC Query" test), and add "Execute HMS script" action to the action profile that assigned to the test to run a script like:
   ExecuteProgram   10000   c:\database\generator.exe   c:\database\database.dbf   c:\HostMon\import1.txt
   NewTestList
   ImportFromFile   c:\HostMon\import1.txt
   SaveTestList   c:\HostMon\temp1.hml
   
   
2. Assuming that you need to monitor 200 web servers in the Internet, but your LAN uses just one router to access to the Internet. Of course if your router goes down, HostMonitor will start hundreds alerts. To avoid unnecessary alerts make next steps:
   - add ping test to check the router;
   - set interval for this test less than intervals for Internet tests (e.g. 30 sec for router and 5 min for each web server);
   - create 2 scripts: one for "Bad" action that will be executed when router will die, another for "Good" action that will be executed when router will restore operability.
   "Bad" script:
   DisableTest _AllTCP
   DisableTest _AllURL
   "Good" script:
   EnableAllTests
   
   If you use HostMonitor version 3.0 or higher, this is not a topical example. You do not need to disable/enable tests, you can just assign router ping test as a Master test for all web tests.

• You can put only one command in each line
• Comments: The program ignores all strings with a semicolon (;) as the 1st character
• Commands: commands are case insensitive (e.g. "LoadTestList" and "LOADTESTLIST" means the same)
• Parameters: parameters are case sensitive
• HostMonitor version 3.0 or higher supports macro variables (%HostName%, %Comment%, %Folder%, etc.). Please note:
  - if script is launched as a result of a test performance, the test's parameters are used for macros;
  - if script is launched manually (using menu File->Execute Script), parameters of the selected test are used for the macros (if no test is selected, macros are not translated)

 Examples:
 NewTestList
 LoadTestList    c:\list1.hml
 AppendTestList  c:\list2.hml
 ImportFromFile  c:\import1.txt  SkipDuplicates  WriteLog
 SaveTestList    c:\list3.hml

  _AllPing        _AllFreeSpace       _AllProcess
  _AllTCP         _AllFolderSize      _AllService
  _AllURL         _AllFileExists      _AllNTLog
  _AllUNC         _AllFileContents    _AllCPU

  _AllInterbase   _AllPostgre         _AllDLL       
  _AllMsSQL       _AllSybase          _AllODBC      
  _AllMySQL       _AllSNMP            _AllSMTP      
  _AllOracle      _AllExternalPrg     _AllPOP3

  _AllIMAP        _AllCountFiles      _AllUDP     
  _AllDNS         _AllRAS             _AllNTP     
  _AllLDAP        _AllPerfCounter     _AllRadius  
  _AllTrace       _AllScript          _AllHTTP    

Examples:
  SetCurrentFolder  Root
  IncludeSubfolders yes

  DisableTest  _AllTCP
  EnableTest   _AllPing
  RefreshTest  _AllURL

  RefreshTest  my router
  EnableTest   server1

Examples:
  SetCurrentFolder   Root\Asia\Ping tests
  IncludeSubFolders  no
  SetTestParam       _AllPing  Timeout        2000
  SetCurrentFolder   Europe
  IncludeSubFolders  yes
  SetTestParam       _AllCPU   UserName       test1
  SetTestParam       _AllCPU   Password       pswd1
  SetTestParam       _AllRAS   Comment        my long ^M multulines ^M comment
  SetTestParam       _AllRAS   CommentLine02  address: 465 Lansdown Ave
  SetTestParam       _AllRAS   CommentLine03  phone: 567-9871
  ReplaceTestParam   _AllTCP   timeout        2000   5000

When defining some of the alert action's parameters you can use special macro variables. There are 5 groups of macro variables:

1. variables that represent parameters of the same test that had triggered an action
2. variables that represent parameters of some explicitly specified test
3. HostMonitor status related macro variables
4. user defined variables (also known as global macro variables)
5. date & time variables

1. variables that represent parameters of the same test that had triggered an action
   
   

   Macro variable	Description
   Test properties
   %TestName%	The name of the test. Has the same value as %HostName%, which has been retained for backward compatibility
   %HostName%	Represents the name of the test (obsolete, retained for backward compatibility. Please, use %TestName% macro instead)
   %HostID%	Represents all numbers in the name of the test. HostMonitor removes all characters from the test's name except decimal numbers and substitutes instead this macro. This macro can be useful when you need to send messages to numeric only pagers (beepers).
   %TestID%	Represents unique ID of the test. TestID is always unique within an HML file
   %Agent%	Represents a name of the remote agent that performs the test, this variable returns the string "HostMonitor" when the test is performed by HostMonitor
   %TestMethod%	Represents short description of a testing method
   %Interval%	The time between two consecutive checks defined for the test
   %ScheduleName%	Name of a schedule assigned to the test
   %AlertProfile%	Name of the action profile
   %AlertThreshold%	Represents condition to set "Bad" status. E.g. for Drive Free Space test this macro will represent minimum limit of free space defined for the test; for TCP test it will display timeout; for CPU Usage test it will show maximum limit for CPU usage value.
   %MasterTest%	Master test name
   %PrivateLog%	The specified private log file name
   %RelatedURL%	Related URL
   %TaskComment%	Test's comment (whole comment, all lines separated by CRLF)
   %CommentLine1%	Represents 1st line of test's comment
   %CommentLine2%	Represents 2nd line of test's comment
   ...	...
   %CommentLine99%	Represents 99th line of test's comment
   %CommentID%	This macro is similar to %HostID%, but uses a test's comment instead the test's name.
   %Folder%	The name of the folder containing the test
   %FullPath%	The full folder path name
   %FolderComment%	Folder's comment (whole comment, all lines separated by CRLF)
   %FCommentLineNN%	Returns a line #NN of a folder`s comment
   %CreatedTime%	The time when the test was created
   %ModifiedTime%	The time when the test was last modified
   Current test state
   %DATE%	Current date
   %TIME%	Current time
   %DateTime%	Current date and time
   %LastTestTime%	Time when the test was last performed
   %Reply%	Represents reply value (depends on the test type, it can be reply time, disk's free space, message from NT Event Log, etc)
   %Status%	Status of the test (text)
   %StatusID%	A 2 digits number that represents status of the test 00- Not Tested 01- Host is Alive 02- No Answer 03- Unknown 04- Not Resolved 05- Checking 06- Resolving 07- Ok 08- Bad 09- Disabled 10- Bad Contents 11- WaitForMaster 12- OutOfSchedule
   %SimpleStatus%	This macro can have one of the three text values: - "UP" for all good statuses (Host is Alive, Ok); - "DOWN" for all bad statuses (No answer, Bad, Bad Contents); - "UNKNOWN" if status of the test is Unknown or Not Resolved.
   Previous state
   To explain following variables we need to explain difference between terms "PreviousStatus" and "LastStatus". "PreviousStatus" is status which test had before current status. "LastStatus" is status which test had after previous check. For example for the last 5 probes test had following statuses: #1-Bad, #2-Unknown, #3-Ok, #4-Ok, #5-Ok (current status is #5-Ok). In this case "PreviousStatus" is #2-Unknown but "LastStatus" is #4-Ok.
   %LastStatus%	Status of the test after previous check ("LastStatus")
   %LastReply%	Reply value returned by previous check
   %PreviousStatusTime%	Represents time when "PreviousStatus" was assigned to the test
   %PreviousStatusDuration%	Represents the duration of the "PreviousStatus". Shows time interval in "[X days] HH:MM:SS" format.
   %PreviousStatusDuration_Sec%	Represents the duration of the "PreviousStatus" in seconds.
   Statistical information
   %Recurrences%	The number of consecutive tests resulting in the same status as the current one
   %StatusChangedTime%	The time when the status last changed
   %StatusChangesCnt%	The number of times the status has changed
   %TotalTests%	Overall tests performed
   %TotalTime%	The time the test has been in monitoring
   %FailedCnt%	The number of "Bad" tests
   %PassedCnt%	The number of "Good" tests
   %UnknownCnt%	The number of "Unknown" tests
   %AliveTime%	The overall time the test has had a "Good" status
   %DeadTime%	The overall time the test has had a "Bad" status
   %UnknownTime%	The overall time the test has had an "Unknown" status
   %AliveRatio%	"Good" to overall tests ratio, in percent
   %DeadRatio%	"Bad" to overall tests ratio, in percent
   %UnknownRatio%	"Unknown" to overall tests ratio, in percent
   %AverageReply%	The average value of the results obtained
   %MinReply%	The minimum value of the results obtained
   %MaxReply%	The maximum value of the results obtained
   Test specific macro variables
   %HostAddr%	Represents the host name (or IP address) of the target system for the following tests: Ping, TCP, Oracle, Interbase, MS SQL, MySQL, Sybase, Postgre, Process, Service, NT Log, CPU Usage, SNMP, SMTP, POP, IMAP, DNS, LDAP, UNC
   following variables have sense for "Service" test only, for other tests these macros return an empty string
   %ServiceComp%	The name of the target computer
   %ServiceName%	The name of the service
   following variables have sense for "Trace" test only, for other tests these macros return an empty string
   %TraceBrief%	Route to the host. Contains IP addresses only
   %TraceFull%	Route to the host. Contains hop number, IP address, and reply time for each hop
   following variables have sense for "NT Event Log" test only, they represent parameters of the last "Bad" event detected:
   %NTEventSource%	Event source. Identifies the software that logged the event
   %NTEventComp%	Name of the computer where the event occurred
   %NTEventTime%	Time of the event
   %NTEventType%	Type of the event
   %NTEventID%	Event identifier
   %NTEventText%	Event description
   %NTEventUser%	Represents the user name if an event is attributed to a specific user

   
   
   

2. variables that represent parameters of some explicitly specified test
   
   If you want to access the parameters of some specific test (not just the one that had triggered an action), specify the name of a test confined by a double colon (::) in front of the name of the macro variable. E.g. if you want to access "Reply" and "Status" fields of the "Ping Yahoo" test, use the following syntax for the variables: %::Ping Yahoo::Reply%, %::Ping Yahoo::Status%
   
   

3. HostMonitor status related macro variables:
   
   These variables represent the status of HostMonitor:

   • %MonitorState% this variable may have 2 values: "Monitoring Started" or "Monitoring Stopped"
   • %AlertsState% this variable may have 2 values: "Alerts Enabled" or "Alerts Disabled"
   
   

4. user defined variables (UDV, also known as global macro variables)
   
   Specifics of user defined variables vs. simple macro variables: macro variables that were described above represent different properties of the tests and you can not change their values directly. Contrary, there are user defined (global) macro variables that can be used in any of the action profiles. This type of variables may be of great use. For example if you have lots of alerts that send e-mails to different mailing lists (one action sends the mail to administrators, another to managers, 3rd action sends notifications to managers and administrators, etc). When some of the e-mail addresses have been changed you will then need to correct these addresses in all profiles that are using them. To avoid this you may define a global variables. Define several variables such as "udv_admingroup = rick@mycompany.com; brand@mycompany.com", "udv_managmentgroup = bob@mycompany.com; john@mycompany.com; kim@mycompany.com", etc and use them as a destination address for the actions: "%udv_admingroup%". Now if any of the e-mail addresses will change, you will have to track this change only in the definition of the variable. This is far more efficient then checking all action profiles that may use the address being changed.
   
   Global variables are defined in the "User Defined Variables" dialog. This dialog is accessible from the menu "Profiles"->"Global macro variables". To add a new variable to the end of the list go to the last existing line and press Down Arrow key. Press INSERT button to insert a new line. Press CTRL+DEL to remove variable. To edit variable press F2.
   
   You can also create an HMScript that will modify variables automatically (for example in respond to some event). Moreover, you may change the value(s) of variables remotely through Telnet Service and any telnet client.
   
   Any name of user defined variable always starts with the prefix "udv_". Even if you will forget to add this prefix to the name HostMonitor will add it automatically. When specifying the name of the variable in action parameter you have to enclose the name in `%`. When HostMonitor performs an action it will substitute the name of the variable by its` current value.
   In the string that represents a value of a UDV you may use the name of another macro variable(s): e.g. date-time variables or test related variables.
   
   

5. date & time variables
   
   To represent a date or time you may use the following variables:
   
   

   %d%	-	Current day as a number without a leading zero (1-31).
   %dd%	-	Current day as a number with a leading zero (01-31).
   %ddd%	-	Current day as an abbreviation (Sun-Sat). HostMonitor uses system's regional settings for abbreviation format.
   %m%	-	Current month as a number without a leading zero (1-12).
   %mm%	-	Current month as a number with a leading zero (01-12).
   %mmm%	-	Current month as an abbreviation (Jan-Dec) using system's regional settings.
   %yy%	-	Current year as a two-digit number (00-99).
   %yyyy%	-	Current year as a four-digit number (0000-9999).

This table illustrates where you can use macro variables:

Action	Macros applicable	Action parameters where macros are applicable
Show message	No
Play sound	No
Generate reports	No
Execute external program	Yes	Command line
Send e-mail (SMTP)	Yes	Address of the sender Destination address Subject Message template
Send message to pager (TAP)	Yes	Message template
Send message to pager (SNPP)	Yes	Message template
Send message to beeper	Yes	Message line
Send message to ICQ	Yes	Subject Message template
Stop/Start/Restart service	Yes	Computer name Service name
Remote reboot	Yes	Computer name
Local reboot	No
Log Event	Yes	Computer name Event source Event description
SQL Query	Yes	SQL Query
Send data to TCP/UDP port	Yes	Init packet Final packet
Syslog	Yes	Message
SNMP Set	Yes	Agent address
SNMP Trap	Yes	Destination address Agent address Enterprise MIB OID MIB Value
Dial-up to the network	No
Disconnect dial-up connection	No
Repeat test	No
Change test interval	No
Execute HMS script	Yes	In the HMS script file

E.g. message template for pager notification can look like: "Hi admin, now %datetime% host %TestName% changes status to %status%. Your monitor."